home *** CD-ROM | disk | FTP | other *** search
/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 4.iso / src / apps / gmemusage / gmemusage.man < prev    next >
Text File  |  1994-08-01  |  17KB  |  360 lines
  1.  
  2.      GMEMUSAGE(1)              UNIX System V              GMEMUSAGE(1)
  3.  
  4.      NAME
  5.           gmemusage - graphical memory usage viewer
  6.  
  7.      SYNOPSIS
  8.           gmemusage [ -i interval ]
  9.                     [ -m | -p | -r | -s ] [ -u ]
  10.                     [ -a aiff-file ] [ -g growth-threshhold ]
  11.                     [ -t thresh ] [ -d delta ]
  12.                     [ progs ... ]
  13.  
  14.      DESCRIPTION
  15.           gmemusage is a graphical memory usage viewer.  gmemusage
  16.           displays a bar chart depicting the breakdown of memory use,
  17.           with each bar labeled with the name of the program using the
  18.           memory and the number of kilobytes of memory used.  If more
  19.           than one copy of a program is running, the number of copies
  20.           is displayed in parentheses after the program name.
  21.  
  22.           In addition, gmemusage will display a breakdown of the
  23.           regions within a program.  Clicking on a bar or program name
  24.           in the main chart will replace the main chart with a chart
  25.           for that program, with each region labeled with one of Text,
  26.           Data, Break, Stack, Shmem, Physical Device, RW, RO, and (if
  27.           possible) the base name of the file or device corresponding
  28.           to each region.  If gmemusage is unable to determine the
  29.           base name of the file or device for a region that does
  30.           correspond to a file or device, gmemusage will display the
  31.           inode number of the file or device.
  32.  
  33.           The meanings of these labels are as follows:
  34.  
  35.           Text      This region contains executable instructions.
  36.                     These instructions most likely came from an
  37.                     executable program file or a dynamic shared
  38.                     object.
  39.  
  40.           Data      This region contains program data.  Regions marked
  41.                     Data are usually associated with a particular
  42.                     executable program file or a dynamic shared
  43.                     object.
  44.  
  45.           Break     Data region that is grown with brk(2).  This is
  46.                     the region that contains memory allocated by
  47.                     malloc(3C).
  48.  
  49.           Stack     Runtime stack.  This is region is used for
  50.                     procecure call frames, and can grow if the program
  51.                     makes deeply nested procedure calls or calls
  52.                     procedures that allocate large amounts of stack
  53.                     space for temporary variables.
  54.  
  55.           Shmem     A System V shared memory region.
  56.  
  57.      Page 1                                          (printed 6/30/94)
  58.  
  59.      GMEMUSAGE(1)              UNIX System V              GMEMUSAGE(1)
  60.  
  61.           Physical Device
  62.                     Region corresponds to a physical device other than
  63.                     main memory, such as a graphics device.
  64.  
  65.           RW        Read/Write data without the Copy on Write bit set.
  66.                     This did not come from an executable program file
  67.                     or a dynamic shared object, and could be a memory
  68.                     mapped file.
  69.  
  70.           RO        Read only data.
  71.  
  72.           U area & PTEs
  73.                     The user area and page table entries.  This is
  74.                     information that the kernel uses to administer a
  75.                     process.
  76.  
  77.           Clicking on the Irix bar in Physical Memory Breakdown mode
  78.           (see below) causes gmemusage to display a breakdown of the
  79.           memory that it is charging to the operating system.
  80.           Separate items include FS Cache, Buffer Data, Heap, Streams,
  81.           Zone, BSD Networking, Page Frame Data, Kernel Tables, Unix
  82.           Data Space, Unix Code Space, Symmon, and Other.
  83.  
  84.           When viewing the breakdown of program memory usage, clicking
  85.           and dragging on the shadow bar will switch the display to
  86.           another program.
  87.  
  88.           The first time a program is clicked on, gmemusage reads in
  89.           information about executables and libraries on the system
  90.           while displaying a wait message.  gmemusage keeps this
  91.           information in its database file $HOME/.gmemusage.inodes.
  92.           if this file does not exist or is older than /unix,
  93.           gmemusage will create it, which can take as long as a
  94.           minute.  If the database already exists and is newer than
  95.           /unix, reading it will only take a few seconds.  See
  96.           ENVIRONMENT VARIABLES below for information on customizing
  97.           $HOME/.gmemusage.inodes.
  98.  
  99.           gmemusage has four different modes of viewing.  The default
  100.           mode, Physical Memory Breakdown, shows the amount of
  101.           physical memory being used by each process, the amount of
  102.           free memory, and the amount of memory being used by Irix.
  103.           The amount of memory charged to each process is calculated
  104.           by taking the pages each process has in memory and pro-
  105.           rating the sizes with the number of processes using each
  106.           page.
  107.  
  108.           The mode Total Sizes of Process shows the the total sizes of
  109.           all the processes in the system.  This corresponds to the SZ
  110.           field of ps(1) output.
  111.  
  112.           The mode Resident Sizes of Processes shows the resident
  113.  
  114.      Page 2                                          (printed 6/30/94)
  115.  
  116.      GMEMUSAGE(1)              UNIX System V              GMEMUSAGE(1)
  117.  
  118.           sizes of all the processes in the system.  This corresponds
  119.           to the RSS field of ps(1) output.
  120.  
  121.           The mode Resident Mappings shows the resident sizes of all
  122.           mapped objects in the system.  A mapped object can
  123.           correspond to an executable file, a dynamic shared object, a
  124.           memory mapped file, or a region attached to a process by
  125.           rld(1).
  126.  
  127.           By default, gmemusage only displays programs that are using
  128.           more than 500 kilobytes of memory; programs using less than
  129.           this are lumped together and labeled < 500.  This threshhold
  130.           is specifiable on the command line and changeable at run
  131.           time.
  132.  
  133.           Alternatively, a list of programs to monitor can be
  134.           specified on the command line (see below).  In this case, a
  135.           bar for each of the programs specified appears (as long as
  136.           that program is running) and any threshhold is ignored.
  137.  
  138.           In addition to the four basic viewing modes and the process
  139.           region breakdown, gmemusage cycles through displays of
  140.           additional information when the 'v' key is pressed.  This
  141.           additional information is a subdivision of each bar in the
  142.           chart, with the right portion of each bar corresponding to
  143.           the additional information.  Down the right side of the
  144.           window the values corresponding to the right portion of each
  145.           bar are displayed.
  146.  
  147.           The following additional information is available:
  148.  
  149.           Private   The portion of each bar that is private memory;
  150.                     that is, memory which is not being shared.  This
  151.                     additional information is available in all modes,
  152.                     except when viewing the Irix breakdown.
  153.  
  154.           Shared    The portion of each bar that is shared between
  155.                     more than one process.  This is calculated by
  156.                     subtracting the Private amount from the Physical
  157.                     amount for each bar.  Shared is available in all
  158.                     modes, except when viewing the Irix breakdown.
  159.  
  160.           Physical  The portion of each bar that is consuming physical
  161.                     memory.  Physical is available in Resident Sizes
  162.                     of Processes and and Total Sizes of Processes
  163.                     modes.
  164.  
  165.           Resident  The portion of each bar that is resident in memory
  166.                     (without taking sharing into acount).  Resident is
  167.                     available in Total Sizes of Processes mode.
  168.  
  169.           If the environment variable USAGESOUND is set to a valid
  170.  
  171.      Page 3                                          (printed 6/30/94)
  172.  
  173.      GMEMUSAGE(1)              UNIX System V              GMEMUSAGE(1)
  174.  
  175.           aiff file, and playaiff(1) is installed, gmemusage will use
  176.           playaiff(1) to play $USAGESOUND when viewing a program's
  177.           region breakdown and the program grows by a threshholded
  178.           amount.  The command line option -a can be used as an
  179.           alternative to the environment for specifying a sound file,
  180.           and the growth threshhold can be specified on the command
  181.           line (see below).
  182.  
  183.           gmemusage has the following command line options:
  184.  
  185.           -iinterval
  186.                     Update display every interval milliseconds.  The
  187.                     default in the absence of the -i option is 500.
  188.  
  189.           -m        Start using Resident Mappings mode.
  190.  
  191.           -p        Start using Physical Memory Breakdown mode.  This
  192.                     is the default.
  193.  
  194.           -r        Start using Resident Sizes of Processes mode.
  195.  
  196.           -s        Start using Total Sizes of Processes mode.
  197.  
  198.           -u        Rebuild the inode database $HOME/.gmemusage.inodes
  199.                     even if it isn't older than /unix (see FILES
  200.                     below).
  201.  
  202.           -tthresh  Use thresh kilobytes instead of 500 kilobytes as
  203.                     the starting threshhold.  Programs using less than
  204.                     this amount of memory in a particular view are not
  205.                     displayed separately, but rather are lumped
  206.                     together in a single bar.
  207.  
  208.           -ddelta   Change the threshhold by delta kilobytes when the
  209.                     up and down arrow keys are pressed (see below).
  210.                     The default is to change the threshhold by 50
  211.                     kilobytes.
  212.  
  213.           -aaiff-file
  214.                     Specify an aiff sound file to be played when
  215.                     viewing a program's region breakdown and the
  216.                     program grows by more than a threshhold amount
  217.                     (see -g option).
  218.  
  219.           -ggrowth-threshhold
  220.                     Specify in kilobytes the growth threshhold.  This
  221.                     is the amount a program has to grow before
  222.                     gmemusage will play a sound.  The default is 12.
  223.  
  224.           progs     Any command line arguments following the arguments
  225.                     described above are interpreted as names of
  226.                     programs.  If program names are specified,
  227.  
  228.      Page 4                                          (printed 6/30/94)
  229.  
  230.      GMEMUSAGE(1)              UNIX System V              GMEMUSAGE(1)
  231.  
  232.                     gmemusage only displays the memory usage of the
  233.                     programs specified, with all other programs lumped
  234.                     together in a bar labeled Other.  In this case,
  235.                     any threshhold or delta is ignored.  This is
  236.                     useful when one is interested in the behavior of a
  237.                     particular program or set of programs, such as
  238.                     when testing for memory leaks.
  239.  
  240.         Runtime controls
  241.           Some of gmemusage's display parameters can be modified at
  242.           runtime.  Pressing the 'p' key selects Physical Memory
  243.           Breakdown mode.  Pressing the 'r' key selects Resident Sizes
  244.           of Processes mode.  Pressing the 's' key selects Total Sizes
  245.           of Processes mode.
  246.  
  247.           Pressing the 'v' key cycles through the available additional
  248.           information for the current mode (see above discussion of
  249.           additional information).
  250.  
  251.           The up arrow key increases the threshhold by 50 kilobytes
  252.           (default) or, if the -d option was specified, by delta
  253.           kilobytes.  The down arrow key decreases the threshhold by
  254.           the same amount.  When the threshhold is decreased to 0, all
  255.           progams running are displayed, even those that use no memory
  256.           (such as kernel processes).
  257.  
  258.           In the main view, clicking on a program's bar causes
  259.           gmemusage to display a detailed memory usage chart for that
  260.           program.  In the detailed usage view, clicking on the shadow
  261.           bar switches the program being displayed, and clicking
  262.           outside the shadow bar or pressing the space bar returns to
  263.           the main view.
  264.  
  265.           At any time, pressing the 't' key causes gmemusage to print
  266.           statistics about the current view to the terminal window.
  267.           The fields in each line are separated by tab characters to
  268.           simplify the parsing of the output by other programs (they
  269.           are also padded with spaces).  There are three different
  270.           types of print outs: All Programs, Resident Mappings, and
  271.           program breakdown.  Which gets printed depends on the mode
  272.           gmemusage is in when 't' is pressed.
  273.  
  274.           The 'h' key brings up an on-line help screen, and the space
  275.           bar returns from there to viewing memory.  The escape key
  276.           exits.
  277.  
  278.      EXAMPLES
  279.           gmemusage -p -t 1000 -d 100
  280.  
  281.           Bring up gmemusage in Physical Memory Breakdown mode, with
  282.           programs using 1000 kilobytes or more of memory displayed
  283.           separately in their own bars.  The up and down arrow keys
  284.  
  285.      Page 5                                          (printed 6/30/94)
  286.  
  287.      GMEMUSAGE(1)              UNIX System V              GMEMUSAGE(1)
  288.  
  289.           will increase and decrease the threshhold by 100 kilobytes
  290.           respectively.
  291.  
  292.           gmemusage -r xwsh toolchest 4Dwm Xsgi fm
  293.  
  294.           Bring up gmemusage in Resident Sizes of Processes mode.
  295.           Display bars for xwsh(1), toolchest(1), 4Dwm(1), Xsgi(1),
  296.           and fm(1).  All other programs will be combined into a bar
  297.           labeled Other.
  298.  
  299.      FILES
  300.           $HOME/.gmemusage.inodes    Table of files that are likely to
  301.                                      correspond to regions mapped into
  302.                                      processes, along with inode
  303.                                      numbers.  gmemusage builds this
  304.                                      table if it doesn't exist or if
  305.                                      it is older than /unix or if the
  306.                                      -u option is supplied, and uses
  307.                                      it to label the bars when viewing
  308.                                      memory breakdown within a
  309.                                      process.  See ENVIRONMENT
  310.                                      VARIABLES below for information
  311.                                      on altering how
  312.                                      $HOME/.gmemusage.inodes is built.
  313.  
  314.           /proc                      gmemusage gets memory usage
  315.                                      information for processes from
  316.                                      the /proc file system.
  317.  
  318.      ENVIRONMENT VARIABLES
  319.           USAGESOUND    If set, $USAGESOUND is used as an aiff file to
  320.                         be played by playaiff(1) when viewing a
  321.                         process's region breakdown and the process
  322.                         grows (see above).
  323.  
  324.           USAGEPATH     Colon separated list of directories to
  325.                         recursively search when building the inode
  326.                         database, $HOME/.gmemusage.inodes.  If
  327.                         USAGEPATH is not found in the environment,
  328.                         gmemusage uses the following default path:
  329.  
  330.           /usr/ToolTalk:/usr/bin:/usr/lib:/usr/local:/usr/Cadmin:
  331.           /usr/CaseVision:/usr/sbin:/usr/bsd:/usr/etc:/lib:/sbin:
  332.           /bin:/etc:/usr/gfx
  333.  
  334.      BUGS
  335.           The totals displayed for the breakdown of a program's
  336.           regions do not always add up exactly to the amount of memory
  337.           in the main view.  In Physical Memory mode, this discrepancy
  338.           is due to rounding error.  In Total Size mode, this is often
  339.           due to the inclusion of physical devices in the breakdown.
  340.           The Resident Size discrepancies are currently being studied.
  341.  
  342.      Page 6                                          (printed 6/30/94)
  343.  
  344.      GMEMUSAGE(1)              UNIX System V              GMEMUSAGE(1)
  345.  
  346.           Beware of "shared object amortization".  When a program that
  347.           uses a shared object (e.g. libXm.so) is started, the memory
  348.           usage of all other programs that use that shared object can
  349.           decrease.  This is because the amount of memory charged to
  350.           each program for shared object usage is prorated based on
  351.           the amount of sharing.
  352.  
  353.           If you have problems, questions, or comments, please send
  354.           mail to rogerc@sgi.com.
  355.  
  356.      SEE ALSO
  357.           ps(1), top(1), gr_top, osview(1), gr_osview(1), proc(4).
  358.  
  359.      Page 7                                          (printed 6/30/94)
  360.